Skip to main content

Contributing

This document provides guidelines and instructions for contributing to the FF-API-External project.

Table of Contents​

Code of Conduct​

Our Pledge​

We are committed to providing a friendly, safe, and welcoming environment for all contributors regardless of experience level, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.

Expected Behavior​

  • Use welcoming and inclusive language
  • Be respectful of differing viewpoints and experiences
  • Gracefully accept constructive criticism
  • Focus on what is best for the community
  • Show empathy towards other community members

Unacceptable Behavior​

Unacceptable behaviors include: intimidating, harassing, abusive, discriminatory, derogatory, or demeaning conduct.

Getting Started​

To contribute to FF-API-External, follow these steps:

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/yourusername/ff-api-external.git
    cd ff-api-external
  3. Set up the development environment: 
    python3.11 -m venv venv
    source venv/bin/activate
    pip install -r requirements.txt
  4. Create a new branch for your changes: 
    git checkout -b feature/your-feature-name
  5. Make your changes
  6. Test your changes
  7. Commit your changes
  8. Push to your fork
  9. Submit a pull request

Development Process​

Branching Strategy​

We use a simplified Git flow branching model:

  • main: The main branch contains production-ready code
  • develop: The development branch for integration of features
  • feature/*: Feature branches for new features or changes
  • bugfix/*: Branches for bug fixes
  • hotfix/*: Branches for urgent fixes to production

Always create your feature branches from develop:

git checkout develop
git pull
git checkout -b feature/your-feature-name

Commit Guidelines​

  • Use clear, descriptive commit messages
  • Start with a verb in the present tense (e.g., "Add", "Fix", "Update")
  • Include the component or area affected
  • Keep commits focused on a single change
  • Reference issue numbers when applicable

Example commit messages:

Add GSM Arena device detail fetching functionality
Fix MongoDB connection error handling
Update documentation for API endpoints

Pull Request Process​

  1. Ensure your code follows the project's coding standards
  2. Update the documentation accordingly
  3. Add or update tests as needed
  4. Verify that the code builds and passes all tests
  5. Submit a pull request to the develop branch
  6. Request review from at least one other developer
  7. Address any feedback and make necessary changes
  8. Once approved, a maintainer will merge your pull request

Coding Standards​

Python Style Guide​

We follow PEP 8 for Python code style, with the following additions:

  • Maximum line length is 100 characters
  • Use 4 spaces for indentation (no tabs)
  • Use single quotes for string literals, except for cases when avoiding escaping
  • Use docstrings for all public classes, methods, and functions
  • Use type annotations where appropriate

Documentation Guidelines​

  • Always update documentation when changing functionality
  • Document all classes, methods, and functions with docstrings
  • Use Markdown for documentation files
  • Provide examples where appropriate
  • Keep API documentation up-to-date
  • Document environment variables and configuration options

Example docstring format:

def function_name(param1, param2):
    """
    Brief description of the function.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of the return value

    Raises:
        ExceptionType: Description of when this exception is raised
    """

Error Handling​

  • Use try-except blocks for error handling
  • Catch specific exceptions rather than using bare except statements
  • Log exceptions with appropriate context
  • Return standardized error responses using the JsonResponse utility
  • Do not expose sensitive information in error messages

Example:

@blueprint.route('/api/endpoint', methods=['GET'])
def api_endpoint():
    try:
        # Implementation...
        return resp.returnResponse(200, result)
    except ValueError as e:
        logging.error(f"Value error in api_endpoint: {str(e)}")
        return resp.returnResponse(400, f"Invalid input: {str(e)}")
    except Exception as e:
        logging.error(f"Unexpected error in api_endpoint: {str(e)}")
        return resp.returnResponse(500, "An unexpected error occurred")

Testing​

We use a combination of unit tests, integration tests, and manual testing to ensure code quality.

Unit Tests​

  • Write unit tests for all new functionality
  • Use pytest as the testing framework
  • Ensure tests are independent and can run in any order
  • Mock external dependencies and APIs
  • Aim for high test coverage of critical components

Example test:

def test_is_valid_email():
    validator = Validation()
    # Valid email
    assert validator.is_valid_email("[email protected]") == True
    # Invalid emails
    assert validator.is_valid_email("test@") == False
    assert validator.is_valid_email("[email protected]") == False
    assert validator.is_valid_email("test") == False

Running Tests​

# Run all tests
pytest

# Run tests with coverage
pytest --cov=.

# Run specific tests
pytest tests/test_file.py

Security Considerations​

When contributing code, pay special attention to security:

  • Do not commit sensitive information (API keys, credentials, etc.)
  • Use environment variables for configuration
  • Validate all user input
  • Use parameterized queries for database operations
  • Follow the principle of least privilege
  • Implement proper authentication and authorization
  • Use HTTPS for all external API calls
  • Be cautious with dependency updates

Code Review Guidelines​

For Authors​

  • Keep pull requests focused on a single change
  • Add a clear description of the changes
  • Highlight any significant design decisions
  • Note any potential issues or areas of concern
  • Respond to reviewer feedback promptly
  • Be open to suggestions and criticism

For Reviewers​

  • Be respectful and constructive
  • Focus on the code, not the author
  • Consider the context and requirements
  • Review for functionality, security, performance, and maintainability
  • Provide specific suggestions for improvement
  • Approve only when you're satisfied with the changes

Thank you for contributing to FF-API-External!